# 导入Web框架和相关库
from flask import Flask, request, jsonify  # Flask Web框架
import numpy as np                         # 数值计算库

# 创建Flask应用实例
app = Flask(__name__)

# 模拟预训练模型 - 用于演示API功能
class MockModel:
    """模拟机器学习模型类"""
    def predict(self, features):
        """模拟预测方法
        Args:
            features: 输入特征列表
        Returns:
            tuple: (预测结果, 置信度)
        """
        # 简单的模拟预测逻辑 - 基于特征平均值
        score = sum(features) / len(features)  # 计算特征平均值
        prediction = 1 if score > 0.5 else 0   # 根据阈值判断类别
        confidence = abs(score - 0.5) * 2      # 计算置信度
        return prediction, confidence

# 创建模型实例
model = MockModel()

# 定义根路径路由 - 提供API基本信息
@app.route('/')
def home():
    """API首页 - 返回API文档信息"""
    return jsonify({
        "message": "AI预测服务 API",
        "endpoints": {
            "predict": "/predict (POST)",    # 预测接口
            "health": "/health (GET)"        # 健康检查接口
        }
    })

# 定义健康检查路由
@app.route('/health')
def health_check():
    """健康检查端点 - 确认服务正常运行"""
    return jsonify({"status": "healthy", "service": "AI Prediction API"})

# 定义预测路由 - 核心业务逻辑
@app.route('/predict', methods=['POST'])
def predict():
    """预测接口 - 接收特征数据并返回预测结果
    请求格式: {"features": [数值列表]}
    返回格式: {"prediction": 预测结果, "confidence": 置信度, ...}
    """
    try:
        # 获取请求数据 - 解析JSON格式的请求体
        data = request.get_json()

        # 验证请求数据完整性
        if not data or 'features' not in data:
            # 返回错误信息和HTTP状态码400(请求错误)
            return jsonify({"error": "缺少 features 字段"}), 400

        features = data['features']

        # 验证输入数据类型
        if not isinstance(features, list):
            return jsonify({"error": "features 必须是数组"}), 400

        # 执行预测 - 调用模型的predict方法
        prediction, confidence = model.predict(features)

        # 返回预测结果 - 使用jsonify自动转换为JSON格式
        return jsonify({
            "prediction": int(prediction),      # 预测类别
            "confidence": float(confidence),    # 预测置信度
            "features_used": len(features)      # 使用的特征数量
        })

    # 异常处理 - 捕获所有可能的错误
    except Exception as e:
        return jsonify({"error": str(e)}), 500  # 返回错误信息和500状态码

def run_api():
    """运行API服务 - 启动Web服务器"""
    print("=== AI预测服务 ===")
    print("启动中...")
    print("访问 http://127.0.0.1:5000 查看API信息")
    print("发送POST请求到 http://127.0.0.1:5000/predict 进行预测")
    print('示例请求体: {"features": [0.1, 0.5, 0.8, 0.3]}')
    print("\n按 Ctrl+C 停止服务")

    # 启动Flask应用
    # host: 监听地址, port: 端口号, debug: 调试模式, use_reloader: 禁用重载器
    app.run(host='127.0.0.1', port=5000, debug=True, use_reloader=False)

# 程序入口点
if __name__ == "__main__":
    run_api()
